Konfiguracja TypeScript: Kompleksowy przewodnik po tsconfig.json

TypeScript, nadzbiór JavaScriptu, wprowadza statyczne typowanie do dynamicznego świata tworzenia stron internetowych. Dobrze skonfigurowany plik tsconfig.json jest kluczowy do wykorzystania pełnej mocy TypeScript. Ten przewodnik stanowi kompleksowy przegląd pliku tsconfig.json, omawiając niezbędne opcje kompilatora, konfigurację projektu oraz zaawansowane ustawienia.

Czym jest tsconfig.json?

Plik tsconfig.json to plik konfiguracyjny, który określa opcje kompilatora dla projektu TypeScript. Informuje on kompilator TypeScript, jak transpiliwać kod TypeScript na JavaScript. Plik ten jest niezbędny do zdefiniowania struktury projektu, ustawienia reguł kompilacji i zapewnienia spójności w zespole deweloperskim, niezależnie od tego, czy zespół znajduje się w jednym biurze, czy jest rozproszony po wielu kontynentach.

Tworzenie pliku tsconfig.json

Aby utworzyć plik tsconfig.json, przejdź do głównego katalogu projektu w terminalu i uruchom następujące polecenie:

            tsc --init
            

              
                Copy
              
            
          

To polecenie generuje podstawowy plik tsconfig.json z powszechnie używanymi opcjami kompilatora. Możesz następnie dostosować plik do specyficznych wymagań swojego projektu. Typowy tsconfig.json będzie zawierał opcje takie jak compilerOptions, include i exclude.

Podstawowe opcje kompilatora

Sekcja compilerOptions jest sercem pliku tsconfig.json. Zawiera szeroki zakres opcji, które kontrolują zachowanie kompilatora TypeScript. Oto niektóre z najważniejszych opcji kompilatora:

target

Opcja target określa docelową wersję ECMAScript dla generowanego kodu JavaScript. Popularne wartości to ES5, ES6 (ES2015), ES2016, ES2017, ES2018, ES2019, ES2020, ES2021, ES2022, ESNext. Wybór odpowiedniego celu jest kluczowy dla zapewnienia kompatybilności z docelowym środowiskiem uruchomieniowym, takim jak przeglądarki czy wersje Node.js.

Przykład:

            {
  "compilerOptions": {
    "target": "ES2020"
  }
}
            

              
                Copy
              
            
          

module

Opcja module określa styl generowania kodu modułów. Popularne wartości to CommonJS, AMD, System, UMD, ES6 (ES2015), ES2020 i ESNext. Wybór systemu modułów zależy od środowiska docelowego i używanego bundlera modułów (np. Webpack, Rollup, Parcel). Dla Node.js często używa się CommonJS, podczas gdy dla nowoczesnych aplikacji internetowych preferowane jest ES6 lub ESNext z bundlerem modułów. Użycie ESNext pozwala deweloperom korzystać z najnowszych funkcji i optymalizacji, polegając na bundlerze w kwestii ostatecznego formatu modułu.

Przykład:

            {
  "compilerOptions": {
    "module": "ESNext"
  }
}
            

              
                Copy
              
            
          

lib

Opcja lib określa listę plików bibliotecznych, które mają być dołączone do kompilacji. Te pliki biblioteczne dostarczają definicje typów dla wbudowanych API JavaScript i API przeglądarek. Popularne wartości to ES5, ES6, ES2015, ES2016, ES2017, ES2018, ES2019, ES2020, ES2021, ES2022, ESNext, DOM, WebWorker, ScriptHost, ES2015.Core, ES2015.Collection, ES2015.Iterable, ES2015.Promise, ES2015.Proxy, ES2015.Reflect, ES2015.Generator, ES2015.Symbol, ES2015.Symbol.WellKnown, ES2016.Array.Include, ES2017.object, ES2017.Intl, ES2017.SharedMemory, ES2017.String, ES2017.TypedArrays, ES2018.Intl, ES2018.Promise, ES2018.RegExp, ES2019.Array, ES2019.Object, ES2019.String, ES2019.Symbol, ES2020.BigInt, ES2020.Promise, ES2020.String, ES2020.Symbol.WellKnown, ES2021.Promise, ES2021.String, ES2021.WeakRef, ES2022.Error, ES2022.Object, ES2022.String i wiele innych. Wybór odpowiednich bibliotek zapewnia, że kompilator TypeScript ma niezbędne informacje o typach dla środowiska docelowego. Użycie biblioteki DOM pozwala projektowi kompilować kod, który używa API specyficznych dla przeglądarki, bez błędów typów.

Przykład:

            {
  "compilerOptions": {
    "lib": ["ES2020", "DOM"]
  }
}
            

              
                Copy
              
            
          

allowJs

Opcja allowJs pozwala kompilatorowi TypeScript kompilować pliki JavaScript razem z plikami TypeScript. Jest to przydatne do stopniowej migracji istniejących projektów JavaScript na TypeScript. Ustawienie tej opcji na true umożliwia kompilatorowi przetwarzanie plików .js, co pozwala na stopniowe wdrażanie TypeScript w projekcie.

Przykład:

            {
  "compilerOptions": {
    "allowJs": true
  }
}
            

              
                Copy
              
            
          

jsx

Opcja jsx określa, jak ma być obsługiwana składnia JSX. Popularne wartości to preserve, react, react-native i react-jsx. preserve zachowuje składnię JSX w pliku wyjściowym, podczas gdy react przekształca JSX na wywołania React.createElement. react-jsx używa nowej transformacji JSX wprowadzonej w React 17, która nie wymaga importowania React. Wybór odpowiedniej opcji JSX jest kluczowy dla projektów używających React lub innych bibliotek opartych na JSX.

Przykład:

            {
  "compilerOptions": {
    "jsx": "react-jsx"
  }
}
            

              
                Copy
              
            
          

declaration

Opcja declaration generuje odpowiadające pliki deklaracji .d.ts dla każdego pliku TypeScript. Pliki deklaracji zawierają informacje o typach i są używane przez inne projekty TypeScript do konsumowania skompilowanego kodu. Generowanie plików deklaracji jest niezbędne do tworzenia bibliotek i modułów wielokrotnego użytku. Pliki te pozwalają innym projektom TypeScript zrozumieć typy i interfejsy udostępniane przez bibliotekę bez konieczności kompilowania oryginalnego kodu źródłowego.

Przykład:

            {
  "compilerOptions": {
    "declaration": true
  }
}
            

              
                Copy
              
            
          

sourceMap

Opcja sourceMap generuje pliki mapy źródeł, które mapują wygenerowany kod JavaScript z powrotem na oryginalny kod TypeScript. Mapy źródeł są niezbędne do debugowania kodu TypeScript w przeglądarkach i innych środowiskach. Gdy w kodzie JavaScript wystąpi błąd, mapa źródeł pozwala deweloperowi zobaczyć odpowiedni kod TypeScript w debuggerze, co ułatwia identyfikację i naprawę problemu.

Przykład:

            {
  "compilerOptions": {
    "sourceMap": true
  }
}
            

              
                Copy
              
            
          

outDir

Opcja outDir określa katalog wyjściowy dla generowanych plików JavaScript. Ta opcja pomaga zorganizować wynik kompilacji projektu, oddzielając kod źródłowy od skompilowanego kodu. Użycie outDir ułatwia zarządzanie procesem budowy i wdrażanie aplikacji.

Przykład:

            {
  "compilerOptions": {
    "outDir": "dist"
  }
}
            

              
                Copy
              
            
          

rootDir

Opcja rootDir określa główny katalog projektu TypeScript. Kompilator używa tego katalogu jako podstawy do rozwiązywania nazw modułów. Ta opcja jest szczególnie ważna w projektach o złożonej strukturze katalogów. Prawidłowe ustawienie rootDir zapewnia, że kompilator może znaleźć wszystkie niezbędne moduły i zależności.

Przykład:

            {
  "compilerOptions": {
    "rootDir": "src"
  }
}
            

              
                Copy
              
            
          

strict

Opcja strict włącza wszystkie opcje ścisłego sprawdzania typów. Jest to wysoce zalecane dla nowych projektów TypeScript, ponieważ pomaga wychwytywać potencjalne błędy na wczesnym etapie procesu deweloperskiego. Włączenie trybu ścisłego wymusza rygorystyczniejsze reguły sprawdzania typów, co prowadzi do bardziej niezawodnego i łatwiejszego w utrzymaniu kodu. Dobrą praktyką jest włączanie trybu ścisłego we wszystkich nowych projektach TypeScript.

Przykład:

            {
  "compilerOptions": {
    "strict": true
  }
}
            

              
                Copy
              
            
          

esModuleInterop

Opcja esModuleInterop umożliwia interoperacyjność między modułami CommonJS i ES. Jest to ważne w projektach, które używają obu typów modułów. Gdy esModuleInterop jest włączone, TypeScript automatycznie obsługuje różnice między modułami CommonJS i ES, ułatwiając importowanie i eksportowanie modułów między tymi dwoma systemami. Ta opcja jest szczególnie przydatna podczas pracy z bibliotekami firm trzecich, które mogą używać różnych systemów modułów.

Przykład:

            {
  "compilerOptions": {
    "esModuleInterop": true
  }
}
            

              
                Copy
              
            
          

moduleResolution

Opcja moduleResolution określa, w jaki sposób TypeScript rozwiązuje importy modułów. Popularne wartości to Node i Classic. Strategia rozwiązywania modułów Node jest domyślna i opiera się na algorytmie rozwiązywania modułów w Node.js. Strategia rozwiązywania modułów Classic jest starsza i rzadziej używana. Użycie strategii Node zapewnia, że TypeScript może poprawnie rozwiązywać importy modułów w środowisku Node.js.

Przykład:

            {
  "compilerOptions": {
    "moduleResolution": "Node"
  }
}
            

              
                Copy
              
            
          

baseUrl i paths

Opcje baseUrl i paths służą do konfigurowania rozwiązywania modułów dla importów niewzględnych. Opcja baseUrl określa katalog bazowy do rozwiązywania nazw modułów niewzględnych. Opcja paths pozwala mapować nazwy modułów na konkretne lokalizacje w systemie plików. Opcje te są szczególnie przydatne w projektach o złożonej strukturze katalogów i do upraszczania importów modułów. Użycie baseUrl i paths może uczynić kod bardziej czytelnym i łatwiejszym w utrzymaniu.

Przykład:

            {
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@components/*": ["src/components/*"],
      "@utils/*": ["src/utils/*"]
    }
  }
}
            

              
                Copy
              
            
          

Opcje Include i Exclude

Opcje include i exclude określają, które pliki powinny być uwzględnione w kompilacji, a które powinny być wykluczone. Opcje te używają wzorców glob do dopasowywania nazw plików. Użycie include i exclude pozwala kontrolować, które pliki są przetwarzane przez kompilator TypeScript, co poprawia wydajność budowania i zmniejsza liczbę błędów. Dobrą praktyką jest jawne określenie plików, które mają być uwzględnione w kompilacji.

Przykład:

            {
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}
            

              
                Copy
              
            
          

Opcja Extends

Opcja extends pozwala dziedziczyć opcje kompilatora z innego pliku tsconfig.json. Jest to przydatne do współdzielenia wspólnych ustawień konfiguracyjnych między wieloma projektami lub do tworzenia konfiguracji bazowych. Użycie opcji extends promuje ponowne wykorzystanie kodu i redukuje duplikację. Dobrą praktyką jest tworzenie konfiguracji bazowych i rozszerzanie ich w poszczególnych projektach.

Przykład:

            {
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "jsx": "react-jsx"
  },
  "include": ["src/**/*"]
}
            

              
                Copy
              
            
          

Konfiguracje zaawansowane

Poza podstawowymi opcjami kompilatora, tsconfig.json obsługuje zaawansowane konfiguracje dla specjalistycznych scenariuszy.

Kompilacja przyrostowa

W przypadku dużych projektów kompilacja przyrostowa może znacznie skrócić czas budowania. TypeScript może buforować wyniki poprzednich kompilacji i rekompilować tylko te pliki, które uległy zmianie. Włączenie kompilacji przyrostowej może drastycznie skrócić czas budowania dużych projektów. Jest to szczególnie ważne w projektach z dużą liczbą plików i zależności.

            {
  "compilerOptions": {
    "incremental": true,
    "tsBuildInfoFile": ".tsbuildinfo"
  }
}
            

              
                Copy
              
            
          

Referencje do projektów

Referencje do projektów pozwalają na strukturyzację dużych projektów TypeScript w mniejsze, niezależne moduły. Może to poprawić czas budowania i organizację kodu. Używanie referencji do projektów może uczynić duże projekty bardziej zarządzalnymi i łatwiejszymi w utrzymaniu. Dobrą praktyką jest używanie referencji do projektów w dużych, złożonych projektach.

            {
  "compilerOptions": {
    "composite": true
  },
  "references": [
    { "path": "./module1" },
    { "path": "./module2" }
  ]
}
            

              
                Copy
              
            
          

Niestandardowe definicje typów

Czasami może być konieczne dostarczenie definicji typów dla bibliotek JavaScript, które ich nie posiadają. Można tworzyć niestandardowe pliki .d.ts, aby zdefiniować typy dla tych bibliotek. Tworzenie niestandardowych definicji typów pozwala używać bibliotek JavaScript w kodzie TypeScript bez utraty bezpieczeństwa typów. Jest to szczególnie przydatne podczas pracy ze starszym kodem JavaScript lub bibliotekami, które nie dostarczają własnych definicji typów.

            // custom.d.ts
declare module 'my-library' {
  export function doSomething(x: number): string;
}
            

              
                Copy
              
            
          

Najlepsze praktyki

• Używaj trybu ścisłego (Strict Mode): Włącz opcję strict dla lepszego sprawdzania typów.
• Określ docelową wersję (Target): Wybierz odpowiednią wersję target dla swojego środowiska uruchomieniowego.
• Organizuj pliki wyjściowe: Używaj outDir do oddzielenia kodu źródłowego od skompilowanego.
• Zarządzaj zależnościami: Używaj include i exclude do kontrolowania, które pliki są kompilowane.
• Wykorzystuj dziedziczenie (Extends): Dziel się wspólnymi ustawieniami konfiguracyjnymi za pomocą opcji extends.
• Zapisuj konfigurację w systemie kontroli wersji: Dodawaj plik `tsconfig.json` do repozytorium git, aby utrzymać spójność między środowiskami deweloperskimi i potokami CI/CD.

Rozwiązywanie typowych problemów

Konfiguracja pliku tsconfig.json może czasami być wyzwaniem. Oto kilka typowych problemów i ich rozwiązania:

Problemy z rozwiązywaniem modułów

Jeśli napotkasz błędy rozwiązywania modułów, upewnij się, że opcja moduleResolution jest poprawnie skonfigurowana, a opcje baseUrl i paths są prawidłowo ustawione. Sprawdź dwukrotnie ścieżki określone w opcji paths, aby upewnić się, że są poprawne. Zweryfikuj, czy wszystkie niezbędne moduły są zainstalowane w katalogu node_modules.

Błędy typów

Błędy typów mogą wystąpić, jeśli definicje typów są nieprawidłowe lub ich brakuje. Upewnij się, że masz zainstalowane poprawne definicje typów dla wszystkich używanych bibliotek. Jeśli używasz biblioteki JavaScript, która nie ma definicji typów, rozważ utworzenie niestandardowych definicji typów.

Błędy kompilacji

Błędy kompilacji mogą wystąpić, jeśli w kodzie TypeScript znajdują się błędy składniowe lub błędy typów. Dokładnie przejrzyj komunikaty o błędach i napraw wszelkie błędy składniowe lub błędy typów. Upewnij się, że twój kod jest zgodny z konwencjami kodowania TypeScript.

Podsumowanie

Dobrze skonfigurowany plik tsconfig.json jest niezbędny dla pomyślnego projektu TypeScript. Rozumiejąc podstawowe opcje kompilatora i zaawansowane konfiguracje, możesz zoptymalizować swój przepływ pracy, poprawić jakość kodu i zapewnić kompatybilność z docelowym środowiskiem. Czas zainwestowany w prawidłową konfigurację tsconfig.json zwróci się w dłuższej perspektywie, redukując błędy, poprawiając łatwość utrzymania i usprawniając proces budowy. Skutkuje to bardziej wydajnym i niezawodnym tworzeniem oprogramowania. Informacje zawarte w tym artykule mają na celu być uniwersalnie stosowane i powinny stanowić solidną podstawę do rozpoczęcia nowego projektu z TypeScript.

Pamiętaj, aby konsultować się z oficjalną dokumentacją TypeScript w celu uzyskania najbardziej aktualnych informacji i szczegółowych wyjaśnień wszystkich dostępnych opcji kompilatora. Dokumentacja TypeScript jest cennym źródłem wiedzy do zrozumienia zawiłości konfiguracji TypeScript.